Retrieving Atoms and Atom Data1

QTGetNextChildType

The QTGetNextChildType function returns the next atom type in the child list of the specified parent atom.



 
pascal QTAtomType QTGetNextChildType (QTAtomContainer container,

                     QTAtom parentAtom,

                     QTAtomType currentChildType);

container: Specifies the atom container that contains the parent atom.
parentAtom: Specifies the parent atom for this operation.
currentChildType: Specifies the last atom type retrieved by this function.
function result: The atom type.

DISCUSSION

You can call this function to iterate through the atom types in a parent atom's child list. To retrieve the first atom type, you should set the value of the currentChildType parameter to 0. To retrieve subsequent atom types, you should set the value of the currentChildType parameter to the atom type retrieved by the previous call to this function.

QTCountChildrenOfType

The QTCountChildrenOfType function returns the number of atoms of a given type in the child list of the specified parent atom.



 
pascal short QTCountChildrenOfType (QTAtomContainer container,

                     QTAtom parentAtom,

                     QTAtomType childType);

container: Specifies the atom container that contains the parent atom.
parentAtom: Specifies the parent atom for this operation.
childType: Specifies the atom type for this operation.
function result: The number of atoms of the specified type in the parent atom's child list.

DISCUSSION

You can call this function to determine the number of atoms of a specified type in a parent atom's child list. To retrieve the total number of atoms in the child list, you should set the value of the childType parameter to 0. If the total number of atoms in the parent atom's child list is 0, the parent atom is a leaf atom.

QTFindChildByIndex

The QTFindChildByIndex function retrieves an atom by index from the child list of the specified parent atom.



 
pascal QTAtom QTFindChildByIndex (QTAtomContainer container,

                     QTAtom parentAtom,

                     QTAtomType atomType,

                     short index,

                     QTAtomID *id);

container: Specifies the atom container that contains the parent atom.
parentAtom: Specifies the parent atom for this operation.
atomType: Specifies the type of the atom to be retrieved.
index: Specifies the index of the atom to be retrieved.
id: Contains a pointer to an uninitialized QTAtomID data structure. On return, if the atom specified by index was found, the QTAtomID data structure contains the atom's ID.
function result: The child atom, if found; otherwise, 0.

DISCUSSION

You call this function to search for and retrieve an atom by its type and index within that type from a parent atom's child list. If you do not want this function to return the atom's ID, set the value of the id parameter to nil .

QTFindChildByID

The QTFindChildByID function retrieves an atom by ID from the child list of the specified parent atom.



 
pascal QTAtom QTFindChildByID (QTAtomContainer container,

                     QTAtom parentAtom,

                     QTAtomType atomType,

                     QTAtomID id,

                     short *index);

container: Specifies the atom container that contains the parent atom.
parentAtom: Specifies the parent atom for this operation.
atomType: Specifies the type of the atom to be retrieved.
id: Specifies the ID of the atom to be retrieved.
index: Contains a pointer to an uninitialized short integer. On return, if the atom specified by id was found, the integer contains the atom's index.
function result: The child atom, if found; otherwise, 0.

DISCUSSION

You call this function to search for and retrieve an atom by its type and ID from a parent atom's child list. If you do not want this function to return the atom's index, set the value of the index parameter to nil .

QTNextChildAnyType

The QTNextChildAnyType function returns the next atom in the child list of the specified parent atom.



 
pascal OSErr QTNextChildAnyType (QTAtomContainer container,

                     QTAtom parentAtom,

                     QTAtom currentChild,

                     QTAtom *nextChild);

container: Specifies the atom container that contains the parent atom.
parentAtom: Specifies the parent atom for this operation.
currentChild: Specifies the last atom retrieved by this function.
nextChild: Contains a pointer to an uninitialized QTAtom data structure. On return, the data structure contains the offset of the next atom in the child list after the atom specified by currentChild , or 0 if the atom specified by currentChild was the last atom in the list.

DISCUSSION

You can call this function to iterate through all the atoms in a parent atom's child list, regardless of their types and IDs. To retrieve the first atom in the child list, set the value of the currentChild parameter to 0.

RESULT CODES

`noErr`	0	No error
`paramErr`	-50	Invalid parameter specified
`invalidAtomErr`	-2106	Atom specified by container and offset does not exist, container may be invalid

QTCopyAtomDataToHandle

The QTCopyAtomDataToHandle function copies the specified leaf atom's data to a handle.



 
pascal OSErr QTCopyAtomDataToHandle (QTAtomContainer container,

                     QTAtom atom,

                     Handle targetHandle);

container: Specifies the atom container that contains the leaf atom.
atom: Specifies the leaf atom whose data should be copied.
targetHandle: Contains a handle. On return, the handle contains the atom's data. The handle must not be locked.

DISCUSSION

You call this function, passing an initialized handle, to retrieve a copy of a leaf atom's data. This function resizes the handle, if necessary.

RESULT CODES

`noErr`	0	No error
`paramErr`	-50	Invalid parameter specified
`memLockedErr`	-117	Trying to move a locked block
`notLeafAtomErr`	-2102	Atom specified by container and offset is not a leaf atom

Memory Manager errors, as documented in Inside Macintosh: Memory .

QTCopyAtomDataToPtr

The QTCopyAtomDataToPtr function copies the specified leaf atom's data to a buffer.



 
pascal OSErr QTCopyAtomDataToPtr (QTAtomContainer container,

                     QTAtom atom,

                     Boolean sizeOrLessOK,

                     long size,

                     void *targetPtr,

                     long *actualSize);

container: Specifies the atom container that contains the leaf atom.
atom: Specifies the leaf atom whose data should be copied.
sizeOrLessOK: Specifies whether the function may copy fewer bytes than the number of bytes specified by the size parameter.
size: Specifies the length, in bytes, of the buffer pointed to by the targetPtr parameter.
targetPtr: Contains a pointer to a buffer. On return, the buffer contains the atom data.
actualSize: Contains a pointer to a long integer which, on return, contains the number of bytes copied to the buffer.

DISCUSSION

You call this function, passing a data buffer, to retrieve a copy of a leaf atom's data. The buffer must be large enough to contain the atom's data. The buffer may be larger than the amount of atom data if you set the value of the sizeOrLessOK parameter to true . You can determine the size of an atom's data by calling QTGetAtomDataPtr .

This function may move memory.

RESULT CODES

`noErr`	0	No error
`paramErr`	-50	Invalid parameter specified
`notLeafAtomErr`	-2102	Atom specified by container and offset is not a leaf atom

Memory Manager errors, as documented in Inside Macintosh: Memory .

QTGetAtomTypeAndID

The QTGetAtomTypeAndID function retrieves an atom's type and ID.



 
pascal OSErr QTGetAtomTypeAndID (QTAtomContainer container,

                     QTAtom atom,

                     QTAtomType *atomType,

                     QTAtomID *id);

container: Specifies the atom container that contains the atom.
atom: Specifies the atom whose type and ID should be retrieved.
atomType: Contains a pointer to an atom type. On return, this parameter points to the type of the specified atom. You can pass nil for this parameter if you do not need this information.
id: Contains a pointer to an atom ID. On return, this parameter points to the ID of the specified atom. You can pass nil for this parameter if you do not need this information.

DISCUSSION

You call this function to retrieve the type and ID for a particular atom.

RESULT CODES

`noErr`	0	No error
`invalidAtomErr`	-2106	Atom specified by container and offset does not exist, container may be invalid